C Cross Referencing tool `cxref'

A program that can automatically generate documentation and cross references for a C program.
The input is any C program with appropriate comments and the output is LaTeX or HTML files.

Program Options

The name of the program is cxref.

Usage: cxref
             filename [ ... filename]
             [-Idirname]
             [-Ddefine] [-Udefine]
             [-CPP cpp_program]
             [-Odirname]
             [-Nbasename]
             [-all-comments]
             [-xref[-all][-file][-func][-var][-type]]
             [-warn[-all][-comment][-xref]]
             [-index[-all][-file][-func][-var][-type]]
             [-raw]
             [-latex|-latex2e]
             [-html]

filename

The name of the file to document, any number of files may be documented at a time.

-Idirname

GCC option to specify the path for include files.

-Ddefine

GCC option to define a pre-processor symbol.

-Udefine

GCC option to undefine a pre-processor symbol.

-CPP program

The name of the program to use instead of the compile time default. The program must be able to perform all of the actions that `gcc -E -C -dD' does to work. If the program takes arguments then the whole thing needs to be in quotes so that it is interpreted as a single argument to cxref.

-Odirname

The name of a directory to use for the output latex files and the location of the cross reference files that are created.

-Nbasename

The name to use for the first part of the output and cross reference files instead of cxref, the file extensions remain the same.

-all-comments

In case you are lazy and think that the existing comments might work, (see below for description of special comments).
[Danger! This option can produce weird results.]

-xref

Produce cross referencing information (see below).

-all: All cross references.
-file: Cross references for files.
-func: Cross references for functions.
-var: Cross references for variables.
-type: Cross references for types.

-warn

Produce warnings, the options must be concatenated together:

-all: All warnings.
-comment: Warn of missing comments.
-xref: Warn of missing cross references.

-index

Produce a cross reference index, the options must be concatenated together:

-all: All indexes.
-file: Index of files.
-func: Index of functions.
-var: Index of variables.
-type: Index of types.

-raw

Produce a raw form of output, not really of much use except with -warn.

-latex

Produce a LaTeX file to document each of the source files and also an extra file that includes each of these files.

-latex2e Produce the LaTeX file for use with the LaTeX2e version.

-html

Produce an HTML file to document each of the source files and a main file to reference each of these files.

Program Documentation Comments

The documentation for the program is produced from comments in the code that are appropriatly formatted. The cross referencing comes from the code itself and requires no extra work.
The special comments are `/**** ****/' (for a file) and `/*++++ ++++*/' (for a data object) any number of `*' or `+' can be used inside of the standard `/*' and `*/' comment delimiters in the comments, they are ignored.
In any situation where a comment follows a `,', `;' or `)' separated only by spaces and tabs, the comment is pushed to before the punctuation to apply to object there.
The program is implemented using a full ANSI C grammar parser with some GCC extensions, this means that the style of the code is unimportant, only the content and comments.

Automated Comment Insertion

To simplify the insertion of comments that will be parsed by cxref, the file cxref.el provides a number of Emacs lisp functions. To use them add the line (load "cxref") to your `.emacs' file or type M-x load-file cxref.el from within Emacs.

The functions and key bindings are:

Control-C Control-F: Adds file comments, a /** **/ header at the top of the file and if it is a .h file then it also adds a #ifndef, #define at the beginning and #endif at the end to stop multiple inclusions.
Control-C f: Adds comments to a function, the cursor must be on the line containing the start of the function definition when this function is called. The /*+ ... +*/ comment that is added is of the header type (see the examples) not inline.
Control-C v: Adds a leading comment to the variable or other definition on the current line.
Control-C e: Adds a trailing comment at the end of the line.
Control-C i: Adds an inline comment that is ignored by cxref.

C Preprocessor

To improve the output that is available a modified version of the GNU CPP V2.6.3 is supplied (named cxref-cpp).
Some comment styles are only available if cxref-cpp is used, see the `Example Special Comments' section of this README.
The #include filenames are also full pathnames if cxref-cpp is not used.
To enable this option, the Makefile for cxref must be modified when cxref is compiled, the variable CPP_TO_USE must be set to point at the place where the C preprocessor is to be installed. If CPP_TO_USE is defined to an empty value then `gcc -E -C -dD' is used as the C preprocessor and the extra features are not available.
To see which option is enabled, run cxref with no arguments, this prints the name of the preprocessor that is used, if the command is `cxref-cpp' then the option is enabled.

Example Special Comments

See the README.c file, to see that the comments are indeed seen in the code, the result of running this through cxref is in README.c.html.
The comments only available with the cxref-cpp pre-processor are indicated.

Cross Referencing

The cross referencing is performed for the following items

Files: The files that the current file is included in (even when included via other files).
#includes: Files included in the current file.
Files included by these files etc.
Variables: The location of the definition of external variables.
The files that have visibility of global variables.
The files / functions that use the variable.
Functions: The file that the function is prototyped in.
The functions that the function calls.
The functions that call the function.
The files and functions that reference the function.
The variables that are used in the function.

Each of these items is cross referenced in the output.
The cross referencing uses files `cxref.variable', `cxref.function', `cxref.include' and `cxref.typedef' in the output directory.
These are a complete list of the function and variable usage in the program and could be used to generate a function call hierarchy or variable usage diagram for example.
Two cxref passes of each file is needed, the first to build up the cross referencing files and the second to use them.
(The file names are different if the `-N' option is used.)

LaTeX Output

The default LaTeX output is a file for each of the source files with one extra file `cxref.tex' that includes each of the other files. This is to allow a makefile to only update the changed files (although the references may require all of the files to be checked again). When the cxref.tex file has been written it can be modified by the user, any new files that are added are added at the end before the table of contents, the rest of the file being unchanged.
The index is written to a file called `cxref.apdx.tex' and cxref.tex is updated to refer to it.
Also written out are two LaTeX style files `page.sty' and `fonts.sty', these use a smaller margin and smaller font to allow more to appear on a page.
(The file names `cxref.tex' and `cxref.apdx.tex' are different if the `-N' option is used.)

HTML Output

The default HTML output is a file for each of the source files with one extra file `cxref.html' that includes each of the other files. This is to allow a makefile to only update the changed files (although the references may require all of the files to be checked again). When the cxref.html file has been written it can be modified by the user, any new files that are added are added at the end before the table of contents, the rest of the file being unchanged.
The index is written to a file called `cxref.apdx.html' and cxref.html is updated to refer to it.
(The file names `cxref.html' and `cxref.apdx.html' are different if the `-N' option is used.)

As an example, the cross referencing produced by cxref for the cxref program itself starts in the file doc/cxref.html. This is a good example of the type of output that can be produced using cxref.

AUTHOR and Copyright

The cxref program was written by Andrew M. Bishop in 1995,96.
The cxref program is copyright Andrew M. Bishop 1995,96.
email: amb@gedanken.demon.co.uk [Please put cxref in the subject line]
The cxref program can be freely distributed according to the terms of the GNU General Public License (see the file COPYING).